cli-truncate

What is cli-truncate?

The cli-truncate package is designed to truncate a string to a specific length without breaking the words, making it suitable for command-line interfaces where space is limited. It can handle strings with ANSI escape codes, ensuring that the visual formatting is preserved even when the string is truncated.

What are cli-truncate's main functionalities?

Truncate a string to a specific length

This feature allows you to truncate a string to a specified length, ensuring that the output fits within a certain space in the CLI. It's useful for displaying long strings in a limited space.

"const cliTruncate = require('cli-truncate');\nconsole.log(cliTruncate('unicorn', 4)); // => 'uni…'"

Preserve ANSI escape codes

This feature ensures that ANSI escape codes within the string are preserved when truncating. This is particularly useful for maintaining text styles (like colors) in the CLI output.

"const cliTruncate = require('cli-truncate');\nconsole.log(cliTruncate('\u001B[31municorn\u001B[39m', 4)); // => '\u001B[31muni…\u001B[39m'"

Specify the position of the truncation

This feature allows you to specify where the truncation should occur (start, middle, or end), giving you more control over how the truncated string looks.

"const cliTruncate = require('cli-truncate');\nconsole.log(cliTruncate('unicorn', 4, {position: 'middle'})); // => 'un…n'"

Other packages similar to cli-truncate

truncate-utf8-bytes

This package truncates strings based on byte length rather than character count, which is useful for ensuring that the string does not exceed byte limits. However, it does not specifically cater to CLI environments or preserve ANSI escape codes.

README

cli-truncate

Truncate a string to a specific width in the terminal

Gracefully handles ANSI escapes. Like a string styled with chalk. It also supports Unicode surrogate pairs and fullwidth characters.

Install

$ npm install cli-truncate

Usage

const cliTruncate = require('cli-truncate');

cliTruncate('unicorn', 4);
//=> 'uni…'

// Truncate at different positions
cliTruncate('unicorn', 4, {position: 'start'});
//=> '…orn'

cliTruncate('unicorn', 4, {position: 'middle'});
//=> 'un…n'

cliTruncate('\u001B[31municorn\u001B[39m', 4);
//=> '\u001B[31muni\u001B[39m…'

// Truncate Unicode surrogate pairs
cliTruncate('uni\uD83C\uDE00corn', 5);
//=> 'uni\uD83C\uDE00…'

// Truncate fullwidth characters
cliTruncate('안녕하세요', 3);
//=> '안…'

// Truncate the paragraph to the terminal width
const paragraph = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa.';
cliTruncate(paragraph, process.stdout.columns));
//=> 'Lorem ipsum dolor sit amet, consectetuer adipiscing…'

API

cliTruncate(input, columns, [options])

input

Type: string

Text to truncate.

columns

Type: number

Columns to occupy in the terminal.

options

Type: Object

position

Type: string
Default: end
Values: start middle end

Position to truncate the string.

Related

• wrap-ansi - Wordwrap a string with ANSI escape codes
• slice-ansi - Slice a string with ANSI escape codes

License

MIT © Sindre Sorhus